Experimental BBS Explossion 3/Experimental BBS Explossion III.iso/pascal/scanh313.zip/SCANHELP.DOC

Text File | 1993-10-22 | 22KB | 551 lines

SCANHELP - Utility to produce help files from TP source code.

    Version 3.13 - update by D.J. Murdoch to TurboPower's utility.

    This update is copyright (1991, 1993) D.J. Murdoch.  It contains
    public domain code written by TurboPower Software, and code licensed
    from TurboPower and Borland.

SYNTAX

    SCANHELP [options] filespec [filespec...]

     Parses the interface section of Turbo Pascal 4.0 to 7.0 units to
     produce a help file summarizing the public methods, procedures, and
     functions.

    Filespec:  list of input files.  May contain wildcards.

    Options:
       /S    sort the "See also" tables
       /I dirs      search list for include files
       /O filename  output filename
       /FB   write Borland .TPH format
       /FH   write HELPC .HDF format
       /FP   write MAKEHELP .TXT format
       /FT   write TeX .TEX format

SUMMARY

    SCANHELP is designed to produce help files from Turbo Pascal source
    code.  These are good enough to use for your own reference, and
    should serve as a good base for help files that you write for
    others.

    Version 3.13 can produce four kinds of help files:  *.TXT files,
    for use as input to TurboPower Software's MAKEHELP utility; *.TPH
    files, for use with Borland's THELP 3.0 or Pascal 7.0+ IDE; *.TEX
    files, for input to Knuth's TeX text processor (using the LaTeX
    macro package); and *.HDF files, for use with Ron Loewy's Help
    Development Kit. The first two give you instantaneous keyword
    searches; the third gives a professional-looking indexed manual,
    and the last gives you input files that will work with
    help compilers for Windows 3.0 and 3.1, OS/2, and DESQview/X, among
    others.

REQUIREMENTS

    *.TXT:  The TurboPower MAKEHELP utility is needed to compile the
    help file, and their POPHELP utility is needed to view them.
    Contact TurboPower Software at 800-333-4160 or 719-260-9136 for
    details on how to obtain these.

    *.TPH:  These files work directly with the version 7.0 Borland
    Pascal IDEs, and may work with current BC++ IDEs.  You can also use
    version 3.0 (or later?) of the THELP utility for access outside the
    IDE.

    *.TEX:  You'll need a copy of the TeX text processor, the LaTeX
    macro package, and if you want an index, the MakeIndex (or MAKEINDX)
    utility.  There are several good free implementations of this; I
    recommend emTeX, by Eberhard Mattes.  It comes with drivers for
    screen previewers and Postscript, Laserjet, or dot-matrix output.

    *.HDF:  This format is designed for use with version 7.0 of Ron
    Loewy's Help Development Kit, HLPDK70.ZIP.  For most of the target
    formats, you'll also need a separate help compiler:  HC or HC31 for
    Windows, the IPFC compiler for OS/2, DVXHLP10.ZIP for DESQview/X.

AIMS

    SCANHELP version 1 was one of TurboPower's Help Tools, released to
    the public domain in January 1990.  It was designed to create an
    outline for a help database describing the interface to a Turbo
    Pascal unit; the assumption was that the user would make major
    modifications to the outline to produce a polished help system.

    I wanted something different:  I wanted documentation for myself,
    and I wanted it to be easy to produce.  I've found that it's too
    easy for printed documentation to get out of synch with the source
    code when the code is under development; even my online
    documentation kept falling behind, because it was just too much
    trouble to go to the *.TXT file and correct the documentation when I
    made a small change.

    The design aim for SCANHELP 2 was thus to produce complete *.TXT
    files, suitable for input to MAKEHELP.  These were to be good enough
    for internal use without any manual editing.  It was possible to
    customize them by working within the original *.PAS source code;
    duplicate documentation was not necessary.

    SCANHELP 3 has the same aim, but I've added *.TPH capability to give
    it a wider audience.  The *.TEX capability makes it much easier to
    proofread help screens; you don't have to hope that you go through
    every topic, you can print them as a book and read through.

    Some other things I've attempted to do, with varying success:

     - produce documentation for *every* interfaced symbol

     - have a minimal impact on the source code, i.e. existing source
     code should produce reasonable help files without substantial
     changes

     - handle multiple source files, so cross references to other units
     are possible

     - work with Pascal scoping rules, so that cross references are
     easy.

DETAILS of TOPIC CREATION

    SCANHELP is used to create help systems for program libraries. The
    input is one or more Turbo Pascal source code files; the output is
    some form of help file.  This section defines the source files and
    generalities applying to all help file types; below the specifics of
    each are given.

    SCANHELP creates help topics for every interfaced identifier in a
    program: object, method, procedure, function, variable, constant.
    The text of each help topic has several parts:

      - the declaration of the identifier

      - the comments following the declaration, up until the next
      declaration begins.

      - (for identifiers that define a scope, e.g. record or object
      types), lists of the identifiers are added to the help topic to
      serve as cross-references.

      - a "See also" list, if you use the #X directive (see below).

    Most references to other identifiers in the declaration are also
    used to form cross references; for example, if a function has
    declaration

      function MyFunc(a: MyType):MyOtherType;

    it will generally be given cross-references on both the MyType and
    MyOtherType identifiers.  It's also possible to create
    cross-references within the text of a comment by surrounding a name
    with "#" marks.

    Often there will be several different uses of the same identifier in
    a program.  For example, "Init" is commonly used as an object
    constructor name.  SCANHELP uses approximately Pascal scoping rules
    in determining what you're referencing:

      - in a record or object declaration, the local fields/methods are
      in scope

      - if the name isn't found there, then the interfaced identifiers
      are searched

      - if it's still not found, the uses list is searched (in reverse
      order, just like TP does)

      - if not found here, TP would give a compiler error, but SCANHELP
      continues on for one more step:  other units in the library are
      also searched, even if the unit doesn't use them.

    The other difference between the TP search and SCANHELP's search is
    that SCANHELP can resolve forward references.  You can have things
    like

      function FirstFunction:Integer;
      { This is the first function; you should see #SecondFunction#! }

      function SecondFunction:Integer;
      { This is the second function; you should see #FirstFunction#! }

    and SCANHELP will know what both # references are talking about.
    This will occasionally lead to errors, if you have such abominations
    as

      type
        integer = word;
        word = integer;

    which are likely to confuse SCANHELP (and you!).

    If you want to override the search possibility, then you can use a
    qualified name.  For example, #TBase.Init# is fine as a
    cross-reference, provided the usual search rules can find TBase.

DIRECTIVES

    SCANHELP has several directives for customizing its behaviour.
    Directives are placed in the source code before running SCANHELP.

    All directives have the format {#L...} where:
      {  }   are normal comment braces
      #      signals that this is a SCANHELP directive
      L      is a command letter
      ...    are one or more parameters for the directive

    #F

     This directive toggles fixed format mode.  In fixed format mode,
     word wrapping doesn't apply to comments.  Note that word wrapping
     always applies to the declaration of the object.

    #M

     This directive toggles "marked text mode".  The behaviour of this
     depends on the particular help format chosen, but generally
     speaking, it should be used to mark examples of usage.  Note that
     #F can be used to start fixed format within marked text, but text
     marking shouldn't be started within fixed format.

    #T Topic [comment]

     This directive creates a new topic and a new identifier in the
     current scope.  SCANHELP parses it as a new declaration.
     For example:

      type Myrec = record
        { this comment will go into the Myrec topic }
        a : word;
        { this comment will go into the Myrec.a topic }
        {#T about_myrec}
        { this comment will go into a Myrec.about_myrec topic, with
          an embedded cross-reference to #a#. }
        b : word;
        { this comment will go into the Myrec.b topic, with cross
          references to the other two topics. }
        {#X about_myrec a}
      end;

     You can use #X directives after #T; this will create See Also
     entries in the #T topic.  Other #X directives can refer to the #T
     topic, using the topic name, as shown after the Myrec.b comment
     above.

    #X [Object.]Topic [[Object.]Topic...]  Include cross-reference

     This directive specifies that Topic is to be included in the "See
     also" list for the current symbol.

     You can have as many topics in one #X directive as you like. Or,
     you can specify multiple #X directives.  For example, the following
     are equivalent:

       {#X TopicA TopicB TopicC}

     and

       {#X TopicA}
       {#X TopicB}
       {#X TopicC}

    #Z+ / #Z-   Toggle Private

     This directive controls what symbols are included in the help text.
     The default is all interfaced objects, methods, procedures and
     functions. If you want to exclude one or more these symbols, then
     place a {#Z+} directive in front of them and a {#Z-} directive
     following. The Z+ signals that all following symbols are private
     and should not be included in the help text. The Z- turns off the
     "private" attribute.



COMMAND LINE OPTIONS

    Some of SCANHELP's behavior is customized from the command line.
    Here is the command line format:

      SCANHELP [options] unitname [unitname...]

    Options:

      /I dirs    Search list for include files

        If your files have $I directives to include other source,
        SCANHELP will use the directories specified here to find it.

      /S  sort cross-references

        The default behavior for the cross-reference table (the See
        also's) is to present the cross-references in the same order
        they appear in the #X directives in the source code. The /S
        options gives the list in sorted order.

      /O file[.TPH|.TXT|.TEX]   Output filename

        SCANHELP normally names the output filename the same as the
        first unit it scans.  Use this directive to override that
        behaviour.  The default extension is .TXT for a MAKEHELP input
        file, .TPH for Borland help files, .TEX for a TeX file, and
        .HDF for a HELPC source file.

      /FP  Make POPHELP database
      /FB  Make Borland .TPH database [default]
      /FT  Make TeX help file
      /FH  Make HELPC .HDF format

        By default, SCANHELP will produce a compiled .TPH file.  If you
        want to use the output with POPHELP, use /FP, and then
        compile the output with TurboPower's MAKEHELP utility.

MAKEHELP/POPHELP SPECIFICS

    The help file created by SCANHELP will create an index entry for
    every identifier, and will have hypertext links for jumping between
    all cross-references.  The text width will be set to 78 characters
    by a directive at the beginning of the file; when MAKEHELP compiles
    it, all line breaks will be fixed in place at that width.  A single
    topic called Contents will be created in the first place in the
    index, with a list of all documented units.

    The #F directive will stop MAKEHELP from word wrapping, and the #M
    directive will mark the block with ^C characters.  In the default
    POPHELP colour scheme, this changes the text colour to dark blue
    from black.

    The standard process for creating a MAKEHELP help text is as
    follows:

     1. Annotate source listings with # directives.

     2. Run SCANHELP on all files (wildcards ok) with the /FP option,
     and probably a /O option to give the output filename.

     3. Run MAKEHELP to compile the output file into a POPHELP database.

     4. Run POPHELP to load itself as a TSR to use the database.

BORLAND .TPH SPECIFICS

    The help file created by SCANHELP will create an index entry for
    every identifier, with a subtitle from the enclosing scope (i.e. the
    unit name, record type, or object type).  The subtitles will only
    show up in the IDE (THELP ignores them) when there are collisions
    between the names---then there will be a single index entry, with
    multiple subtitles shown below.

    The .TPH will have hypertext links for jumping between all
    cross-references.  No lines will have fixed width unless the #F
    directive is used; the IDE or THELP will re-wrap all of the lines to
    fit in the visible window. A single topic called Contents will be
    created, with a list of all documented units.  It will be the first
    topic that THELP displays.

    The #F directive will stop comment lines from wrapping, and will
    preserve any leading spaces in the comments.

    The #M directive will mark text as a code example, so that the IDE
    will insert it into your text.  Use the Help window local menu
    (Alt-F10 brings this up) to get the option to copy the text to your
    clipboard, then use the usual Shift-Insert command to insert it into
    your edit buffer.

    The standard process for creating a Borland help file is as
    follows:

     1. Annotate source listings with # directives.

     2. Run SCANHELP on all files (wildcards ok) with the /FB (or no /F)
     option, and probably a /O option to give the output filename.

     3.(a) Run THELP with the /Ffilename option to load the database as a
     TSR, or

     3.(b) Load the help database into the IDE by using the /Help Files New
     dialog.  Be sure to hit the OK button (or type K); if you hit Esc, your
     request will be ignored.

TeX SPECIFICS

    The output file produced with the /OT option is meant to be run as a
    single document under the LaTeX macro package.  The SCANHELP.STY
    file is used to define the appearance of the document.  If you make
    no changes to it, then the style will be very similar to the style
    used in the Reference sections of Borland manuals:  major topics
    will be set off with lines, and fields and methods will be shown
    within the major topic defining their type. The index will contain a
    bold face index entry for the definition of every identifier, and a
    standard entry for all cross-references. TeX will fill lines to fit
    your page width.

    The #F directive puts LaTeX into a "verbatim" environment; this uses
    the formatting from your comments in a typewriter style typeface.
    The #M directive marks a block as an example, with a note in the
    margin the way the Borland manuals do it.

    The standard process for creating TeX help document is as follows:

     1. Annotate source listings with # directives.

     2. Run SCANHELP on all files (wildcards ok) with the /FT
     option, and probably a /O option to give the output filename.

     3. Run TeX with LaTeX on the output file.  How to do this will
     depend on your local installation; on mine, it's just

        LATEX filename

     4. Run the MakeIndex program to compile the document index.  With
     the emTeX version of TeX, this is done by

        MAKEINDX filename

     where the filename is your help filename *without the extension*.

     5. Run LATEX again on your file; this time the index will be
     incorporated into the document.

     6. Print the .DVI file using a driver suitable for your printer;
     for example,

        lpr -d filename.dvi

     is the method that works on our network or on many Unix machines.

HelpDK Specifics

     SCANHELP will produce one indexed help topic for each identifier.
     Subtitles aren't supported.  While HelpDK does produce input
     files for both Borland's help compiler and TurboPower's, you'll
     probably get better results using those specific options (/FB and
     /FP) rather than this generic one.

     Neither #F nor #M directives are supported.  They will be stripped
     from the comments and ignored.

     The general procedure to use is as follows.

     1. Annotate your source listings with # directives.

     2. Run SCANHELP on all files (wildcards ok) with the /FH option,
        and probably a /O option to give the output filename.

     3. Run HELPC with the option specific to your target database:

         /PX or /MT   - for HelpDK's own help engine
         /W30 or /W31 - for Windows 3.0/3.1 source
         /TH          - for Borland THELP source
         /QH          - for Microsoft QuickHelp source
         /TV          - for Borland TVHC source
         /PH          - for TurboPower POPHELP source
         /XD          - for DESQview/X source
         /OS2         - for OS/2-IPF Source
         /TXT         - Generate printable .TXT file

     4. See the instructions in the HelpDK file HLPDK.DOC for the final
        compile step suitable to each target.

     For example, for Windows 3.1 the steps would be:

         SCANHELP *.pas /Omyhelp /FH
         HELPC /W31 myhelp
         HC31 myhelp

     where SCANHELP is in this package, HELPC is in the HLPDK70.ZIP package,
     and HC31 is in Microsoft's SDK, or other Windows programming packages
     like Borland Pascal or Turbo Pascal for Windows.


FILES

    SCANHELP.EXE    The executable
    SCANHELP.DOC    This file
    SCANHELP.STY    The TeX style file for help documents
    HELPFILE.PAS    One of the source files to SCANHELP
    HELPFILE.PS     Postscript copy of TeX output from
                      SCANHELP helpfile /ft
                    Print this if you want to see whether it's worth
                    getting TeX.

CHANGE HISTORY

    1.01  10-8-90
        SCANHELP - Changed .Z to #Z to agree with documentation

    1.02  3-7-91
        SCANHELP - Fixed "xref line too long" bug

    2.00Alpha  1-Dec-91
          Major changes by DJM.

    2.00Alpha2 Added /O option.

    2.00Alpha3 Added embedded cross-references.

    2.03  2.00Alpha3 with a more reasonable name. :-)

    2.04  Fixed bug - #Z+ was being ignored by comment saver

    3.00  Added Borland .TPH file and TeX support, changed a lot of the
          formatting, internal structure, and symbol table methods, and
          deleted a lot of the old options.

    3.10  Added .HDF file support, and #F and #M directives, and fixed
          bugs:  SCANHELP no longer asks for a numeric coprocessor; long
          identifiers don't cause trouble.

    3.12:  Fixed bug on #Z+, increased speed for .TPH files.

    3.13:  Fixed bug in fixed line handling.

LICENSE

    This program is shareware, not public domain.  It contains public
    domain code written by TurboPower Software, and makes use of
    copyright libraries by Borland International and TurboPower
    Software, but the majority of the code is written by and belongs to
    Duncan Murdoch.

    You are licensed to distribute this program unchanged, provided you
    charge no more than reasonable distribution costs, and in no case
    more than $10 (US) for it.

    You are also licensed to use it personally at no charge.  This means
    that you may compile and use help files on any number of computers,
    but only if you are their only reader:  you may not distribute them
    to other people.  (Of course, if you distribute your source code to
    other people, you can give them instructions on how to use SCANHELP
    to produce their own personal help files.)

    If you want to distribute help files produced by SCANHELP, you must
    register the program with me.  An additional benefit of registration
    is that I will send you a diskette containing a number of other
    utilities I've written to help with Turbo Pascal programming, DOS
    and Windows.  One of them that is not currently available elsewhere
    is FINDHELP; it searches Borland help files for keywords that aren't
    indexed.  Please tell me your preferred diskette format.

    Registration costs $25 (US or Canadian).  Send a cheque or money
    order for that amount to

      Duncan Murdoch
      337 Willingdon Ave.
      Kingston, Ontario, Canada.
      K7L 4J3

    Source code to SCANHELP is available to registered users for an
    additional $25 (i.e. $50 total).  Recompiling SCANHELP will require
    TurboPower's Object Professional library together with their Turbo
    Analyst package; however, the Borland help file unit requires only
    simple data manipulation routines from Object Professional.

    I'd like to hear bug reports, and suggested improvements.
    Please send those to me at the address above, or by email to one of
    the following addresses:

     Fidonet:    DJ Murdoch at 1:249/99.5
     Internet:   [e-mail]
     Compuserve: 71631,122